public member function

std::operator>> (istream)

single character (1)	istream& operator>> (istream& is, char& c);istream& operator>> (istream& is, signed char& c);istream& operator>> (istream& is, unsigned char& c);
character sequence (2)	istream& operator>> (istream& is, char* s);istream& operator>> (istream& is, signed char* s);istream& operator>> (istream& is, unsigned char* s);

single character (1)

istream& operator>> (istream& is, char& c);istream& operator>> (istream& is, signed char& c);istream& operator>> (istream& is, unsigned char& c);

character sequence (2)

istream& operator>> (istream& is, char* s);istream& operator>> (istream& is, signed char* s);istream& operator>> (istream& is, unsigned char* s);

single character (1)	istream& operator>> (istream& is, char& c);istream& operator>> (istream& is, signed char& c);istream& operator>> (istream& is, unsigned char& c);
character sequence (2)	istream& operator>> (istream& is, char* s);istream& operator>> (istream& is, signed char* s);istream& operator>> (istream& is, unsigned char* s);
rvalue extraction (3)	template<class charT, class traits, class T>basic_istream<charT,traits>& operator>> (basic_istream<charT,traits>&& is, T& val);

single character (1)

istream& operator>> (istream& is, char& c);istream& operator>> (istream& is, signed char& c);istream& operator>> (istream& is, unsigned char& c);

character sequence (2)

istream& operator>> (istream& is, char* s);istream& operator>> (istream& is, signed char* s);istream& operator>> (istream& is, unsigned char* s);

rvalue extraction (3)

template<class charT, class traits, class T>basic_istream<charT,traits>&  operator>> (basic_istream<charT,traits>&& is, T& val);

Extract characters

This operator (>>) applied to an input stream is known as extraction operator, and performs formatted input:

(1) single character: Extracts the next character from is and stores it as the value of c.
(2) character sequence: Extracts characters from is and stores them in s as a c-string, stopping as soon as either a whitespace character is encountered or (width()-1) characters have been extracted (if width is not zero).
A null character (charT()) is automatically appended to the written sequence.
The function then resets width to zero.
(3) rvalue extraction: Allows extracting from rvalue istream objects, with the same effect as from lvalues: It effectively calls: is>>val.

Internally, the function accesses the input sequence of is by first constructing a sentry with noskipws set to false: this may flush its tied stream and/or discard leading whitespaces (see istream::sentry). Then (if good), it extracts characters from is's associated stream buffer object (as if calling its member functions sbumpc or sgetc), and finally destroys the sentry object before returning.

Notice that if this function extracts the last character of a stream when extracting a single character (1), it does not set its eofbit flag, but attempting to extract beyond it does.

Calling this function does not alter the value returned by gcount on is.

Parameters

is: Input stream object from which characters are extracted.
c: Object where the extracted character is stored.
s: Pointer to an array of characters where extracted characters are stored as a c-string.
is's member function width may be used to specify a limit on the number of characters to write.
val: Object where content is stored.
T shall be a type supported as right-hand side argument either by this function or by is's member function operator>>.
charT and traits are the class template parameters of istream (see basic_istream).

Return Value

The istream object (is).

The extracted value or sequence is not returned, but directly stored in the variable passed as argument.

Errors are signaled by modifying the internal state flags:

flag	error
`eofbit`	The function stopped extracting characters because the input sequence controlled by `is` has no more characters available (end-of-file reached).
`failbit`	Either no characters were extracted, or these could not be interpreted as a valid value of the appropriate type.
`badbit`	Error on stream (such as when this function catches an exception thrown by an internal operation). When set, the integrity of the stream may have been affected.

Multiple flags may be set by a single operation.

If the operation sets an internal state flag that was registered with is's member exceptions, the function throws an exception of its failure member type.

Example

// example on extraction
#include <iostream>     // std::cin, std::cout

int main () {
  char str[10];

  std::cout << "Enter a word: ";
  std::cin.width (10);               // limit width
  std::cin >> str;
  std::cout << "The first 9 chars of your word are: " << str << '\n';

  return 0;
}

This example demonstrates the use of some of the overloaded operator>> functions shown above using the standard istream object cin.

Data races

Modifies c or the elements of the array pointed by s.
Modifies is.
Concurrent access to the same stream object may cause data races, except for the standard stream object cin when this is synchronized with stdio (in this case, no data races are initiated, although no guarantees are given on the order in which extracted characters are attributed to threads).

Exception safety

Basic guarantee: if an exception is thrown, all objects involved are in valid states.
It throws an exception of member type failure if the resulting error state flag for is is not goodbit and member exceptions was set to throw for that state in is.
Any exception thrown by an internal operation is caught and handled by the function, setting is's badbit flag. If badbit was set on the last call to exceptions for is, the function rethrows the caught exception.

class templates

classes

manipulators

member classes

member functions

non-member overloads

protected members